home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / directory.z / directory
Encoding:
Text File  |  2002-10-03  |  18.8 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _dddd_iiii_rrrr_eeee_cccc_tttt_oooo_rrrr_yyyy: _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444, _tttt_eeee_llll_llll_dddd_iiii_rrrr, _tttt_eeee_llll_llll_dddd_iiii_rrrr_6666_4444, _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr,
  10.      _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_6666_4444, _rrrr_eeee_wwww_iiii_nnnn_dddd_dddd_iiii_rrrr, _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444______rrrr - directory
  11.      operations
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_dddd_iiii_rrrr_eeee_nnnn_tttt_...._hhhh_>>>>
  15.  
  16.      _DDDD_IIII_RRRR _****_oooo_pppp_eeee_nnnn_dddd_iiii_rrrr _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ffff_iiii_llll_eeee_nnnn_aaaa_mmmm_eeee_))))_;;;;
  17.  
  18.      _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;
  19.  
  20.      _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt_6666_4444 _****_rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444 _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;
  21.  
  22.      _oooo_ffff_ffff______tttt _tttt_eeee_llll_llll_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;
  23.  
  24.      _oooo_ffff_ffff_6666_4444______tttt _tttt_eeee_llll_llll_dddd_iiii_rrrr_6666_4444 _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;
  25.  
  26.      _vvvv_oooo_iiii_dddd _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _oooo_ffff_ffff______tttt _llll_oooo_cccc_))))_;;;;
  27.  
  28.      _vvvv_oooo_iiii_dddd _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_6666_4444 _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _oooo_ffff_ffff_6666_4444______tttt _llll_oooo_cccc_))))_;;;;
  29.  
  30.      _vvvv_oooo_iiii_dddd _rrrr_eeee_wwww_iiii_nnnn_dddd_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;
  31.  
  32.      _iiii_nnnn_tttt _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;
  33.  
  34.      _iiii_nnnn_tttt _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_eeee_nnnn_tttt_rrrr_yyyy_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_****_rrrr_eeee_ssss_))))_;;;;
  35.  
  36.      _iiii_nnnn_tttt _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444______rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt_6666_4444 _****_eeee_nnnn_tttt_rrrr_yyyy_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt_6666_4444
  37.      _****_****_rrrr_eeee_ssss_))))_;;;;
  38.  
  39. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  40.      The inclusion of <_d_i_r_e_n_t._h> selects the System V versions of these
  41.      routines.  For the 4.3BSD versions, include <_s_y_s/_d_i_r._h>.  The 64-bit
  42.      interfaces are not present in the 4.3BSD versions.
  43.  
  44.      _o_p_e_n_d_i_r opens the directory named by _f_i_l_e_n_a_m_e and associates a directory
  45.      stream with it.  _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr returns a pointer to be used to identify the
  46.      directory stream in subsequent operations.  The directory stream is
  47.      positioned at the first entry.  A null pointer is returned if _f_i_l_e_n_a_m_e
  48.      cannot be accessed or is not a directory, or if it cannot _mmmm_aaaa_llll_llll_oooo_cccc(3C)
  49.      enough memory to hold a _DDDD_IIII_RRRR structure or a buffer for the directory
  50.      entries.
  51.  
  52.      _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr returns a pointer to the next active directory entry and
  53.      positions the directory stream at the next entry.  No inactive entries
  54.      are returned.  It returns _NNNN_UUUU_LLLL_LLLL upon reaching the end of the directory or
  55.      upon detecting an invalid location in the directory.  _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr buffers
  56.      several directory entries per actual read operation; _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr marks for
  57.      update the _ssss_tttt______aaaa_tttt_iiii_mmmm_eeee field of the directory each time the directory is
  58.      actually read.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr is a reentrant version of _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr.  The directory entry at the
  75.      current position in _dddd_iiii_rrrr_pppp is copied into _e_n_t_r_y.  The storage pointed to by
  76.      _e_n_t_r_y shall be large enough for a _d_i_r_e_n_t with an array of _c_h_a_r _d__n_a_m_e
  77.      member containing at least {_N_A_M_E__M_A_X} plus one elements.  Upon successful
  78.      return, the pointer returned at *_r_e_s_u_l_t shall have the same value as the
  79.      argument _e_n_t_r_y.  Upon reaching the end of the directory stream, this
  80.      pointer shall have the value _NNNN_UUUU_LLLL_LLLL.
  81.  
  82.      _tttt_eeee_llll_llll_dddd_iiii_rrrr returns the current location associated with the named directory
  83.      stream.
  84.  
  85.      _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr sets the position of the next _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr operation on the directory
  86.      stream.  The new position reverts to the position associated with the
  87.      directory stream at the time the _tttt_eeee_llll_llll_dddd_iiii_rrrr operation that provides _l_o_c was
  88.      performed.  Values returned by _tttt_eeee_llll_llll_dddd_iiii_rrrr are valid only if the directory
  89.      has not changed because of compaction or expansion.  This situation is
  90.      not a problem with System V, but it may be a problem with some file
  91.      system types.
  92.  
  93.      _rrrr_eeee_wwww_iiii_nnnn_dddd_dddd_iiii_rrrr resets the position of the named directory stream to the
  94.      beginning of the directory.  It also causes the directory stream to refer
  95.      to the current state of the corresponding directory, as a call to _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr
  96.      would.
  97.  
  98.      _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr closes the named directory stream and frees the _DDDD_IIII_RRRR structure.
  99.  
  100.      _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444______rrrr, _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_6666_4444, and _tttt_eeee_llll_llll_dddd_iiii_rrrr_6666_4444 are parallel interfaces
  101.      provided for cases where the information returned will not fit in the
  102.      fields in the _dddd_iiii_rrrr_eeee_nnnn_tttt structure.  The fields in question are the inode
  103.      number (_d__i_n_o) and the current offset (_d__o_f_f).  If it is necessary to
  104.      call the 64-bit interfaces, and they are not called, an _EEEE_OOOO_VVVV_EEEE_RRRR_FFFF_LLLL_OOOO_WWWW error
  105.      will result.  The 64-bit _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr and _tttt_eeee_llll_llll_dddd_iiii_rrrr interfaces should not be
  106.      mixed with the non-64-bit interfaces in a sequence of calls.
  107.  
  108.      The following errors can occur as a result of these operations.
  109.  
  110.      _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr returns _NNNN_UUUU_LLLL_LLLL on failure and sets _eeee_rrrr_rrrr_nnnn_oooo to one of the following
  111.      values:
  112.  
  113.      _EEEE_NNNN_OOOO_TTTT_DDDD_IIII_RRRR             A component of _f_i_l_e_n_a_m_e is not a directory.
  114.  
  115.      _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS              A component of _f_i_l_e_n_a_m_e denies search permission.
  116.  
  117.      _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS              Read permission is denied on the specified directory.
  118.  
  119.      _EEEE_MMMM_FFFF_IIII_LLLL_EEEE              The maximum number of file descriptors are currently
  120.                          open.
  121.  
  122.      _EEEE_NNNN_FFFF_IIII_LLLL_EEEE              The system file table is full.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))
  137.  
  138.  
  139.  
  140.      _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT              _f_i_l_e_n_a_m_e points outside the allocated address space.
  141.  
  142.      _EEEE_LLLL_OOOO_OOOO_PPPP               Too many symbolic links were encountered in
  143.                          translating _f_i_l_e_n_a_m_e.
  144.  
  145.      _EEEE_NNNN_AAAA_MMMM_EEEE_TTTT_OOOO_OOOO_LLLL_OOOO_NNNN_GGGG        The length of the _f_i_l_e_n_a_m_e argument exceeds
  146.                          _{{{{_PPPP_AAAA_TTTT_HHHH______MMMM_AAAA_XXXX_}}}}, or the length of a _f_i_l_e_n_a_m_e component
  147.                          exceeds _{{{{_NNNN_AAAA_MMMM_EEEE______MMMM_AAAA_XXXX_}}}} while _{{{{______PPPP_OOOO_SSSS_IIII_XXXX______NNNN_OOOO______TTTT_RRRR_UUUU_NNNN_CCCC_}}}} is in
  148.                          effect.
  149.  
  150.      _EEEE_NNNN_OOOO_EEEE_NNNN_TTTT              A component of _f_i_l_e_n_a_m_e does not exist or is a null
  151.                          pathname.
  152.  
  153.      _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr returns _NNNN_UUUU_LLLL_LLLL on failure and sets _eeee_rrrr_rrrr_nnnn_oooo to one of the following
  154.      values:
  155.  
  156.      _EEEE_NNNN_OOOO_EEEE_NNNN_TTTT              The current file pointer for the directory is not
  157.                          located at a valid entry.
  158.  
  159.      _EEEE_BBBB_AAAA_DDDD_FFFF               The file descriptor determined by the _DDDD_IIII_RRRR stream is
  160.                          no longer valid.  This result occurs if the _DDDD_IIII_RRRR
  161.                          stream has been closed.
  162.  
  163.      _EEEE_DDDD_IIII_RRRR_CCCC_OOOO_RRRR_RRRR_UUUU_PPPP_TTTT_EEEE_DDDD       The directory is corrupted on disk.
  164.  
  165.      _EEEE_OOOO_VVVV_EEEE_RRRR_FFFF_LLLL_OOOO_WWWW           One of the inode number values or offset values did
  166.                          not fit in 32 bits, and the 64-bit interfaces were
  167.                          not used.
  168.  
  169.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL              64-bit and non-64-bit calls were mixed in a sequence
  170.                          of calls.
  171.  
  172.      _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr returns 0 on success and an error value (see above values for
  173.      _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr) on error.
  174.  
  175.      _tttt_eeee_llll_llll_dddd_iiii_rrrr, _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr, and  _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr return -1 on failure and set _eeee_rrrr_rrrr_nnnn_oooo to the
  176.      following value:
  177.  
  178.      _EEEE_BBBB_AAAA_DDDD_FFFF               The file descriptor determined by the _DDDD_IIII_RRRR stream is
  179.                          no longer valid.  This results if the _DDDD_IIII_RRRR stream has
  180.                          been closed.
  181.  
  182.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL              64-bit and non-64-bit calls were mixed in a sequence
  183.                          of calls.
  184.  
  185. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  186.      Here is a sample program that prints the names of all the files in the
  187.      current directory:
  188.  
  189.           _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_iiii_oooo_...._hhhh_>>>>
  190.           _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_dddd_iiii_rrrr_eeee_nnnn_tttt_...._hhhh_>>>>
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))
  203.  
  204.  
  205.  
  206.           _mmmm_aaaa_iiii_nnnn_((((_))))
  207.           _{{{{
  208.                _DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_;;;;
  209.                _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_dddd_iiii_rrrr_eeee_nnnn_tttt_pppp_;;;;
  210.  
  211.                _dddd_iiii_rrrr_pppp _==== _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr_(((( _""""_...._"""" _))))_;;;;
  212.                _wwww_hhhh_iiii_llll_eeee _(((( _((((_dddd_iiii_rrrr_eeee_nnnn_tttt_pppp _==== _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_(((( _dddd_iiii_rrrr_pppp _))))_)))) _!!!!_==== _NNNN_UUUU_LLLL_LLLL _))))
  213.                     _((((_vvvv_oooo_iiii_dddd_))))_pppp_rrrr_iiii_nnnn_tttt_ffff_(((( _""""_%%%%_ssss_\\\\_nnnn_""""_,,,, _dddd_iiii_rrrr_eeee_nnnn_tttt_pppp_----_>>>>_dddd______nnnn_aaaa_mmmm_eeee _))))_;;;;
  214.                _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr_(((( _dddd_iiii_rrrr_pppp _))))_;;;;
  215.                _rrrr_eeee_tttt_uuuu_rrrr_nnnn _((((_0000_))))_;;;;
  216.           _}}}}
  217.  
  218. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  219.      _gggg_eeee_tttt_dddd_eeee_nnnn_tttt_ssss(2), _mmmm_kkkk_dddd_iiii_rrrr(2), _rrrr_mmmm_dddd_iiii_rrrr(2), _mmmm_aaaa_llll_llll_oooo_cccc(3C), _ssss_cccc_aaaa_nnnn_dddd_iiii_rrrr(3C), _dddd_iiii_rrrr_eeee_nnnn_tttt(4),
  220.      _dddd_iiii_rrrr_eeee_cccc_tttt_oooo_rrrr_yyyy______bbbb_ssss_dddd(3B).
  221.  
  222. NNNNOOOOTTTTEEEESSSS
  223.      These functions overwrite the buffer as needed, so applications should
  224.      copy data to preserve it.
  225.  
  226.      The _tttt_eeee_llll_llll_dddd_iiii_rrrr_((((_)))) and _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_((((_)))) functions used long in place of off_t prior
  227.      to IRIX 6.2.  This change makes no difference in the o32 and 64 bit
  228.      compilation environments, but in the n32 compilation environment source
  229.      that used to use a long may need to be changed to use an off_t instead.
  230.  
  231. BBBBUUUUGGGGSSSS
  232.      The prototypes for _tttt_eeee_llll_llll_dddd_iiii_rrrr_((((_)))) and _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_((((_)))) in dirent.h use long rather
  233.      than off_t in the o32 and 64 bit compilation environments.  This is
  234.      harmless, however, because long and off_t are identical in these
  235.      environments.
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.